PP-0: code standards with a shrink-only baseline; one atomic writer, one grammar helper - #65

PP-0 of the v0.4.0 plan (preprocessing-design-v0.4.md revision 4, §8 and §9): tooling and dedup, with no behaviour change. Its own diff adds tooling, dedup and a baseline; it changes no behaviour.

Merge order: #64 (PP-1, merged) is already in this branch (1fa7ccb), so the baseline covers the combined code.

Summary

• tools/code_rules.py: the shared file copied from MorphoFeature origin/main (9951a58), extended with §9:
  • the private-docstring rule: private functions over 10 executable lines need a docstring;
  • the layer check: each package module is declared pure, io, ui or orchestration in pyproject.toml. Pure modules may not import I/O or UI modules, or call open, print, read_text and the like; UI modules may not import scipy;
  • RESERVED_NAMES: shared logic listed by its owner repository (normalization, preprocessing, CellPatcher). A definition anywhere else fails;
  • a baseline that may only shrink. baseline_key drops line numbers, so code that moves keeps its entry. New or grown violations fail, and so do entries the code no longer needs;
  • a # noqa count ratchet for C901, PLR0913, PLR0915 and ANN, counting line and file-level (ruff: noqa:) comments in src, tools and tests.
• tools/check.py: runs ruff, pytest and the code rules.
  • --rules runs only the code rules; the CI lint job runs it.
  • --update-baseline only lowers the baseline.
• Ruff now selects C90 (max 15), PLR0913 (max 8), PLR0915 (max 50), ANN, PGH004 (a noqa must name its rules) and I002 (from __future__ import annotations in every module of src and tools).
  • Existing sites carry # noqa, counted by the ratchet: 63 ANN, 2 C901, 3 PLR0913 (one in tests/zarr_tree.py) and 2 PLR0915.
  • Tests are exempt from ANN and I002, as they already are from D. The experiment scripts are exempt as run; notebooks from I002.
  • Two annotations were added instead of a noqa: planes._tiff_blocking's keyframe, and the notebook's Step 0 function.
• tools/code_rules_baseline.json: the 113 violations present in PP-1: the axis check (swaps and contradictions are errors; plain stacks confirmed) #64 + main (oversized files and functions, private functions without docstrings, duplicated test helpers).
• Dedup (audit D1, D7):
  • _io.write_text_atomic replaces the three temp-file-then-os.replace copies (design.py, manifest.py, mask_scan.py);
  • validation.agree replaces _are/_contain (discovery) and _do/_their/_are/_match/_have (masks).
• Docs: a "Code standards" section in development.md; AGENTS.md "Done means" now refers to tools/check.py.

Review fixes (0608025)

• A bare # noqa or # ruff: noqa: … hid rules from the ratchet (both passed --rules). Now PGH004 refuses the bare form, and file-level codes and tests' comments are counted.
• baseline_key used the first number of an "identical bodies" message, a line number, as its size: moving a duplicated helper down failed as "grew". Line numbers and digits inside names are no longer sizes; those four entries are lowered to 0.
• §9's from __future__ import annotations was not enforced; I002 now does (added to __init__.py and __main__.py).

Notes for review

• The SHA-256 test pins this extended copy, with line endings normalised to LF. MorphoFeature's copy has to be updated to the same file for the "identical in every repo" rule; this PR does not edit other repositories.
• Owner question: tests are exempt from ANN here (2,367 test sites); MorphoFeature annotates its tests. Should this repo annotate its tests too, as a follow-up?
• The layer check is deliberately simple: it looks at imports and call names. The existing modules are classified so that none violates its layer.
• The baseline file can still be edited by hand; shrink-only is enforced against the code, so a hand edit that adds an entry shows only in the diff. A follow-up could compare it with origin/main's baseline in CI.

Tests

• New tests:
  • tests/test_code_rules.py (18): the shared-file SHA; the repository against its baseline; every module has a layer; ruff guards for ANN001, C901, PLR0913, PGH004 and I002; size and suppress guards; private docstrings; layers; reserved names; the baseline's shrink and grow rules; line numbers are never sizes; line and file-level noqa counts.
  • tests/test_shared_helpers.py (4): write_text_atomic and agree.
• All of these fail on old main, where tools/, _io and agree do not exist.
• Full gate as CI (ruff check, ruff format --check, tools/check.py --rules, pytest with .[dev,notebook,zarr]):
  • Python 3.13 with zarr 3: 1579 passed, 1 skipped (running as root ignores file modes).
  • Python 3.11 with zarr 2.18: 1561 passed, 19 skipped (that root skip plus 18 OME-NGFF 0.5 tests that need zarr 3).

🤖 Generated with Claude Code

https://claude.ai/code/session_01WX6rdMV1r5jUPUR94kxV5a